943e71
@@ -1957,6 +1957,12 @@
public class CollectionUtils {
      * in <code>collection</code> unless <code>remove</code> contains <code>e</code>, in which
      * case the cardinality is zero. This method is useful if you do not wish to modify
      * the collection <code>c</code> and thus cannot call <code>collection.removeAll(remove);</code>.
+     * <p>
+     * This implementation iterates over <code>collection</code>, checking each element in
+     * turn to see if it's contained in <code>remove</code>. If it's not contained, it's added
+     * to the returned list. As a consequence, it is advised to use a collection type for
+     * <code>remove</code> that provides a fast (e.g. O(1)) implementation of
+     * {@link Collection#contains(Object)}.
      *
      * @param <E>  the type of object the {@link Collection} contains
      * @param collection  the collection from which items are removed (in the returned collection)
